Add Sphinx/Doxygen/Breathe documentation framework for phlex::experimental API by Copilot · Pull Request #323 · Framework-R-D/phlex

Copilot · 2026-02-13T17:09:09Z

Adds a Sphinx + Doxygen + Breathe documentation scaffold under docs/ to generate API reference documentation for key phlex::experimental types, along with dependency requirements and gitignore entries for generated outputs.

Documentation framework

docs/Doxyfile: Doxygen configuration for XML output consumed by Breathe
docs/source/conf.py: Sphinx configuration with Breathe integration, version 0.1.0 matching CMakeLists.txt
docs/source/index.rst: documentation index with toctree

Dependency pinning

docs/requirements.txt: sphinx>=9.1,<10, breathe>=4.36,<5, sphinx-rtd-theme>=3.1,<4

API pages

RST pages for module_graph_proxy, source_graph_proxy, graph_proxy, framework_graph, registrar, declared_transform, declared_fold, declared_unfold, product_store, products
module_graph_proxy and source_graph_proxy are the primary user-facing plugin entry points (from phlex/module.hpp and phlex/source.hpp) for writing algorithm modules and data sources

Doxyfile configuration

FILE_PATTERNS = *.hpp *.cpp, EXCLUDE_PATTERNS = */detail/*
PREDEFINED macros updated for current codebase (BOOST_DLL_ALIAS, PHLEX_DETAIL_REGISTER_PLUGIN)

Housekeeping

.gitignore: added docs/doxygen/ and docs/build/ for generated output
conf.py: module docstring added for ruff D100 compliance

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

greenc-FNAL · 2026-02-13T18:03:02Z

@copilot I think for maximum clarity, it would be better to reset this branch to upstream/main and then re-do the work following the current philosophy, functions/class structure, etc.

Copilot · 2026-02-13T18:10:33Z

@copilot I think for maximum clarity, it would be better to reset this branch to upstream/main and then re-do the work following the current philosophy, functions/class structure, etc.

Done. In commit 412a5ec I reset the branch to main and removed all the stale files from the old base. In 0712ae9 I fixed the docs to match the current codebase (correct class names, macros, version).

The PR now shows only 13 files changed (135 additions, 0 deletions from main): the docs/ directory with Sphinx/Doxygen/Breathe configuration and API pages, plus .gitignore entries for docs build output.

Copilot

Pull request overview

Adds a Sphinx + Doxygen + Breathe documentation scaffold under docs/ to generate API reference documentation for key phlex::experimental types, along with dependency requirements and gitignore entries for generated outputs.

Changes:

Add Sphinx project entrypoint (index.rst) and minimal conf.py wired to Breathe.
Add API reference .rst pages for several phlex::experimental classes.
Add Doxygen configuration + Python requirements, and ignore generated docs artifacts in .gitignore.

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/source/index.rst	Adds top-level Sphinx landing page and toctree for API pages.
docs/source/conf.py	Adds Sphinx configuration with Breathe integration.
docs/source/api/graph_proxy.rst	Adds API page for `phlex::experimental::graph_proxy`.
docs/source/api/framework_graph.rst	Adds API page for `framework_graph` and `layer_sentry`.
docs/source/api/registrar.rst	Adds API page for `phlex::experimental::registrar`.
docs/source/api/declared_transform.rst	Adds API page for `declared_transform`.
docs/source/api/declared_fold.rst	Adds API page for `declared_fold`.
docs/source/api/declared_unfold.rst	Adds API page for `declared_unfold`.
docs/source/api/product_store.rst	Adds API page for `product_store`.
docs/source/api/products.rst	Adds API page for `products`.
docs/requirements.txt	Adds Python dependencies for building docs.
docs/Doxyfile	Adds Doxygen configuration to emit XML for Breathe.
.gitignore	Ignores generated Doxygen/Sphinx build output directories.

Comments suppressed due to low confidence (1)

docs/requirements.txt:4

The PR description says dependencies are “pinned”, but requirements.txt uses version ranges (e.g., >=9.1,<10) which will allow new releases and can change doc build output over time. Either pin exact versions (e.g., ==...) to match the description, or update the description to reflect that these are minimum/compatible ranges. Also remove the trailing blank line at EOF to avoid generating a 4th empty requirement line.

sphinx>=9.1,<10
breathe>=4.36,<5
sphinx-rtd-theme>=3.1,<4

docs/source/conf.py

greenc-FNAL · 2026-02-13T21:05:26Z

@phlexbot python-fix

github-actions · 2026-02-13T21:06:02Z

Automatic ruff fixes pushed (commit af87c94).
⚠️ Note: Some issues may require manual review and fixing.

codecov · 2026-02-13T21:15:09Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@            Coverage Diff             @@
##             main     #323      +/-   ##
==========================================
- Coverage   86.51%   86.47%   -0.05%     
==========================================
  Files         119      119              
  Lines        2403     2403              
  Branches      387      387              
==========================================
- Hits         2079     2078       -1     
- Misses        206      207       +1     
  Partials      118      118

Flag	Coverage Δ
unittests	`86.47% <ø> (-0.05%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 4 files with indirect coverage changes

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 103c08c...3b11ebf. Read the comment docs.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

greenc-FNAL · 2026-03-04T18:56:38Z

@copilot This PR (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date with respect to the goals of your original prompt for this task.

Copilot · 2026-03-04T18:59:54Z

@copilot This PR (branch copilot/update-branch-with-main-again) has been rebased against main once more: please re-evaluate and bring up to date wi...

Re-evaluated after rebase. The only needed fix was removing the layer_sentry reference from framework_graph.rst — that class was deleted from the codebase since my last update. All other documented classes (graph_proxy, framework_graph, registrar, declared_transform, declared_fold, declared_unfold, product_store, products) verified present. Dependency versions, macros, and project version all still current. Done in 234e183.

greenc-FNAL · 2026-03-04T19:03:36Z

@copilot Does any of the documentation provided need to be updated due to changes in the code, or are there any new classes/files that would have been covered by the goals of the original prompt?

Copilot · 2026-03-04T19:06:34Z

@copilot Does any of the documentation provided need to be updated due to changes in the code, or are there any new classes/files that would have been covered by the goals of the ori...

All currently documented classes remain accurate. Two new user-facing classes were added to the codebase after the original branch was created and are now covered:

phlex::experimental::module_graph_proxy (phlex/module.hpp) — the restricted graph_proxy subinterface users implement for algorithm modules, registering with PHLEX_REGISTER_ALGORITHMS
phlex::experimental::source_graph_proxy (phlex/source.hpp) — the restricted subinterface for data sources, registering with PHLEX_REGISTER_PROVIDERS

Both are now documented in 31b7611.

…work This commit introduces the foundational infrastructure for documenting the C++ codebase using a Sphinx, Doxygen, and Breathe toolchain. Key changes include: - A new `docs/` directory to house all documentation-related files. - Configuration files for Sphinx (`conf.py`) and Doxygen (`Doxyfile`). - A `requirements.txt` file listing the necessary Python dependencies for building the documentation. - The `phlex/core/graph_proxy.hpp` header has been fully documented with Doxygen comments to serve as a style guide and working example. - An initial Sphinx structure in `docs/source/` that integrates the Doxygen XML output via Breathe, making the `graph_proxy` documentation available on the documentation website. Initial plan Update docs: pin latest deps, fix version, expand API coverage, add .gitignore entries Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Reset branch to main and re-apply docs-only changes Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com> Fix docs for current codebase: correct version, class names, macros, and .gitignore Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

…ing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.

Copilot · 2026-03-04T21:09:59Z

docs/Doxyfile

+INPUT             = ../phlex ../form
+OUTPUT_DIRECTORY  = doxygen


INPUT and OUTPUT_DIRECTORY are written as relative paths that only work if Doxygen is invoked from docs/ (e.g., cd docs && doxygen Doxyfile). If someone runs doxygen docs/Doxyfile from the repo root (a common invocation), ../phlex/../form will point outside the repo and the XML will be written to <repo>/doxygen/, which won’t match the Sphinx Breathe path or the .gitignore entries. Consider making these paths robust to the invocation working directory (e.g., repo-root-relative paths) or add a documented wrapper/Makefile target that enforces running from docs/.

Suggested change

INPUT = ../phlex ../form

OUTPUT_DIRECTORY = doxygen

# Paths are relative to the repository root; invoke as: doxygen docs/Doxyfile

INPUT = phlex form

OUTPUT_DIRECTORY = docs/doxygen

Copilot · 2026-03-04T21:09:59Z

docs/source/conf.py

+breathe_projects = {
+    "Phlex": "../doxygen/xml/",
+}


breathe_projects["Phlex"] points to ../doxygen/xml/ relative to docs/source/, which assumes Doxygen writes XML to docs/doxygen/xml. With the current docs/Doxyfile, that location depends on the working directory used when invoking Doxygen, so Sphinx can easily fail to find the XML. Align this path with a Doxygen output location that’s stable (or document/enforce the expected invocation directory).

Copilot AI assigned Copilot and greenc-FNAL Feb 13, 2026

Copilot started work on behalf of greenc-FNAL February 13, 2026 17:09 View session

Copilot AI changed the title ~~[WIP] Update branch with latest main and enhance features~~ Update Sphinx/Doxygen/Breathe docs: pin latest deps, fix config, expand API coverage Feb 13, 2026

Copilot AI requested a review from greenc-FNAL February 13, 2026 17:19

Copilot finished work on behalf of greenc-FNAL February 13, 2026 17:19

Copilot started work on behalf of greenc-FNAL February 13, 2026 18:03 View session

Copilot finished work on behalf of greenc-FNAL February 13, 2026 18:11

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 0712ae9 to 2095c80 Compare February 13, 2026 18:25

greenc-FNAL changed the base branch from jules-feature-sphinx-doxygen-breathe-setup to main February 13, 2026 18:30

greenc-FNAL marked this pull request as ready for review February 13, 2026 18:31

Copilot AI review requested due to automatic review settings February 13, 2026 18:31

Copilot started reviewing on behalf of greenc-FNAL February 13, 2026 18:31 View session

Copilot AI reviewed Feb 13, 2026

View reviewed changes

docs/source/conf.py Outdated Show resolved Hide resolved

Copilot started work on behalf of greenc-FNAL February 13, 2026 20:58 View session

Copilot finished work on behalf of greenc-FNAL February 13, 2026 21:00

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 824f679 to a7a5bf2 Compare February 14, 2026 00:18

greenc-FNAL marked this pull request as draft February 14, 2026 01:19

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch 2 times, most recently from dcbc52d to e416cbc Compare February 20, 2026 17:44

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from e416cbc to 85a095f Compare February 24, 2026 16:32

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 85a095f to a62c7df Compare March 4, 2026 18:52

Copilot started work on behalf of greenc-FNAL March 4, 2026 18:56 View session

Copilot finished work on behalf of greenc-FNAL March 4, 2026 19:00

Copilot started work on behalf of greenc-FNAL March 4, 2026 19:03 View session

Copilot AI changed the title ~~Update Sphinx/Doxygen/Breathe docs: pin latest deps, fix config, expand API coverage~~ Add Sphinx/Doxygen/Breathe documentation framework for phlex::experimental API Mar 4, 2026

Copilot finished work on behalf of greenc-FNAL March 4, 2026 19:07

google-labs-jules bot and others added 6 commits March 4, 2026 13:59

Add module docstring to docs/source/conf.py for ruff D100 compliance

dbf55fc

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Apply ruff fixes

b5ba110

Ignore mypy errors

466cbc4

Remove layer_sentry reference (class no longer exists in codebase)

9e6ef75

Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

Add module_graph_proxy and source_graph_proxy API pages (new user-fac…

3b11ebf

…ing entry points) Co-authored-by: greenc-FNAL <2372949+greenc-FNAL@users.noreply.github.com>

greenc-FNAL force-pushed the copilot/update-branch-with-main-again branch from 31b7611 to 3b11ebf Compare March 4, 2026 19:59

greenc-FNAL marked this pull request as ready for review March 4, 2026 20:58

greenc-FNAL requested a review from Copilot March 4, 2026 21:05

Copilot started reviewing on behalf of greenc-FNAL March 4, 2026 21:06 View session

Copilot AI reviewed Mar 4, 2026

View reviewed changes

-INPUT             = ../phlex ../form
-OUTPUT_DIRECTORY  = doxygen
+# Paths are relative to the repository root; invoke as: doxygen docs/Doxyfile
+INPUT             = phlex form
+OUTPUT_DIRECTORY  = docs/doxygen

Conversation

Copilot AI commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation framework

Dependency pinning

API pages

Doxyfile configuration

Housekeeping

Uh oh!

greenc-FNAL commented Feb 13, 2026

Uh oh!

Copilot AI commented Feb 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

greenc-FNAL commented Feb 13, 2026

Uh oh!

github-actions bot commented Feb 13, 2026

Uh oh!

codecov bot commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

greenc-FNAL commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

greenc-FNAL commented Mar 4, 2026

Uh oh!

Copilot AI commented Mar 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Feb 13, 2026 •

edited

Loading

codecov bot commented Feb 13, 2026 •

edited

Loading